/*
 * Copyright (C) 2012  Romain DUBOIS
 * 
 * This file is part of NeMoS - Network and Modular Software
 * 
 * NeMoS is free software: you can redistribute it and/or modify
 * it under the terms of the GNU General Public License as published by
 * the Free Software Foundation, either version 3 of the License, or
 * (at your option) any later version.
 * 
 * NeMoS is distributed in the hope that it will be useful,
 * but WITHOUT ANY WARRANTY; without even the implied warranty of
 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
 * GNU General Public License for more details.
 * 
 * You should have received a copy of the GNU General Public License
 * along with NeMoS.  If not, see <http://www.gnu.org/licenses/>.
 */
package nemos.util.osgi;

import java.util.Map;

import org.osgi.framework.ServiceReference;

/**
 * IServiceMap : The service map interface.
 * 
 * <p>
 * This interface extends the {@link Map} interface, adding methods to handle
 * both {@link ServiceReference}s and services. This interface is intented to be
 * a tool for tracking services on a specific service property.
 * </p>
 * 
 * @param <S>
 *            The service type
 */
public interface IServiceMap<S> extends Map<String, ServiceReference<S>> {

    /**
     * Get the best matching service.
     * 
     * @param pKey
     *            The required property value
     * @return The best matching service
     */
    S getService(final String pKey);

    /**
     * Add a service reference.
     * 
     * @param pReference
     *            The service reference
     */
    void add(final ServiceReference<S> pReference);

    /**
     * Add a service to the map.
     * 
     * @param pReference
     *            The service reference
     * @param pService
     *            The service object
     */
    void add(final ServiceReference<S> pReference, final S pService);

    /**
     * Remove a service reference from the map.
     * 
     * @param pReference
     *            The service reference to remove
     */
    void remove(final ServiceReference<S> pReference);
}